home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 526-550 / disk_540 / sana / netbuff.doc < prev    next >
Text File  |  1992-05-06  |  18KB  |  661 lines
  1. TABLE OF CONTENTS
  2.  
  3. netbuff.library
  4. netbuff.library/AllocSegments()
  5. netbuff.library/CompactNetBuff()
  6. netbuff.library/CopyFromNetBuff()
  7. netbuff.library/CopyNetBuff()
  8. netbuff.library/CopyToNetBuff()
  9. netbuff.library/FreeSegments()
  10. netbuff.library/IntAllocSegments()
  11. netbuff.library/IntFreeSegments()
  12. netbuff.library/IsContiguous()
  13. netbuff.library/NetBuffAppend()
  14. netbuff.library/PrependNetBuff()
  15. netbuff.library/ReadyNetBuff()
  16. netbuff.library/ReclaimSegments()
  17. netbuff.library/SplitNetBuff()
  18. netbuff.library/TrimNetBuff()
  19. netbuff.library                                               netbuff.library
  20.  
  21.     Netbuff.library maintains the free pool of NetBuffSegments for
  22.     use by the various network modules. It also contains several
  23.     utility functions for dealing with NetBuffs as a data
  24.     structure for "holding" network packet data as well as
  25.     allocators and deallocators for NetBuffSegments.
  26.  
  27.     The intent is for all of the network modules to use a common
  28.     pool of buffers so as to reduce the memory requirements of the
  29.     network software, and for the network modules to be able to
  30.     pass network data (packets) with minimal copying.
  31.  
  32.    STRUCTURES
  33.     A NetBuff is a data structure representing a logical array of
  34.     of bytes.
  35.  
  36.         struct NetBuff
  37.             {
  38.             struct MinList List;
  39.             ULONG Count;
  40.             };
  41.  
  42.         List
  43.             List of NetBuffSegments.
  44.  
  45.         Count
  46.             The number of bytes of data the NetBuff is said to
  47.             contain.
  48.  
  49.  
  50.     A NetBuffSegment is a data structure used to store and keep
  51.     track of all or part of the data in a NetBuff.
  52.  
  53.         struct NetBuffSegment
  54.             {
  55.             struct MinNode Node;
  56.             ULONG PhysicalSize;
  57.             ULONG DataOffset;
  58.             ULONG DataCount;
  59.             UBYTE *Buffer;
  60.             };
  61.  
  62.         Node
  63.             Node structure linking the NetBuffSegments together.
  64.  
  65.         PhysicalSize
  66.             The size of the data area that Buffer points to. If
  67.             this field is zero, the actual size of the data area
  68.             unknown and it is managed (allocated and freed) by
  69.             some other entity. Only 'Count' bytes starting at
  70.             '(Buffer+Offset)' are known to be valid.
  71.  
  72.         DataOffset
  73.             Offset into the Buffer where the data starts.
  74.  
  75.         DataCount
  76.             Number of data bytes that this NetBuffSegment
  77.             contains.
  78.  
  79.         Buffer
  80.             Pointer to the start of the data area for this
  81.             NetBuffSegment.
  82.  
  83.    PHYSICALSIZE ZERO SEGMENTS
  84.     Any software making use of NetBuffs must correctly handle
  85.     NetBuffs with PhysicalSize zero segments. The general rules to
  86.     follow are as follows:
  87.  
  88.     +   "Send" NetBuffs, those NetBuffs where the data is created
  89.         and passed to a lower network layer, are returned to the
  90.         creator with the data intact. This class of NetBuffs may
  91.         have segments of PhysicalSize zero.
  92.  
  93.     +   "Receive" NetBuffs, those NetBuffs where the data is
  94.         created and passed to a higher network layer, are not
  95.         returned to the creator. This class of NetBuffs may not
  96.         have segments of PhysicalSize zero.
  97.  
  98.     +   Lower network layers will eventually return the actual
  99.         NetBuff structure (pointer) to the layer that created the
  100.         data.
  101.  
  102.     +   NetBuffs returned to higher layers from lower layers may
  103.         have the "physical" layout of the data changed. The layout
  104.         of the "logical" data will not have changed.
  105.  
  106.     +   Track NetBuff structures to know when it is safe to reuse/
  107.         deallocate storage for PhysicalSize zero segments.
  108.  
  109.     In to above, higher and lower network layers refers to the
  110.     usual diagram of the OSI network layering model; where the
  111.     application layer is at the top of the diagram and the
  112.     physical layer is at the bottom.
  113.  
  114.     This model for handling PhysicalSize zero segments also has
  115.     obvious advantages in situations where time-outs and
  116.     retransmittions occure.
  117.  
  118.    CREDITS
  119.     Raymond S. Brand   rsbx@cbmvax.commodore.com   (215) 431-9100
  120.     Martin Hunt      martin@cbmvax.commodore.com   (215) 431-9100
  121.     Perry Kivolowitz           ASDG Incorporated   (608) 273-6585
  122.  
  123. netbuff.library/AllocSegments()               netbuff.library/AllocSegments()
  124.  
  125.    NAME
  126.     AllocSegments -- Get a list of NetBuffSegments.
  127.  
  128.    SYNOPSIS
  129.     AllocSegments( Count, Segment_List )
  130.                    D0     A0
  131.  
  132.     void AllocSegments( ULONG, struct List * );
  133.  
  134.    FUNCTION
  135.     This function returns a list of NetBuffSegments sufficient to
  136.     hold Count bytes.
  137.  
  138.    INPUTS
  139.     Count           Numbers of bytes for which space is needed.
  140.     Segment_List    Pointer to an empty (initialized) list to hold
  141.                         the allocated NetBuffSegments.
  142.  
  143.    RESULTS
  144.  
  145.    NOTES
  146.     The function cannot be called from interrupts.
  147.  
  148.    SEE ALSO
  149.     netbuff.library/IntAllocSegments(),
  150.     netbuff.library/FreeSegments(),
  151.     netbuff.library/ReadyNetBuff()
  152.  
  153.    BUGS
  154.  
  155. netbuff.library/CompactNetBuff()             netbuff.library/CompactNetBuff()
  156.  
  157.    NAME
  158.     CompactNetBuff -- Optimize a NetBuff.
  159.  
  160.    SYNOPSIS
  161.     error = CompactNetBuff( Netbuff )
  162.     D0                      A0
  163.  
  164.     LONG CompactNetBuff( struct NetBuff * );
  165.  
  166.    FUNCTION
  167.     This function optimizes a NetBuff by moving the data to fill
  168.     each needed NetBuffSegment as much as possible and return
  169.     unused NetBuffSegments to the free pool. This function will
  170.     not modify NetBuffSegments of physical size zero.
  171.  
  172.    INPUTS
  173.     Netbuff         Pointer to NetBuff structure to optimize.
  174.  
  175.    RESULTS
  176.     error           Zero if successful; non-zero otherwise.
  177.  
  178.    NOTES
  179.     This function consumes time.
  180.  
  181.    SEE ALSO
  182.  
  183.    BUGS
  184.  
  185. netbuff.library/CopyFromNetBuff()           netbuff.library/CopyFromNetBuff()
  186.  
  187.    NAME
  188.     CopyFromNetBuff -- Copy data from a NetBuff to memory.
  189.  
  190.    SYNOPSIS
  191.     error = CopyFromNetBuff( Netbuff, Offset, Data, Count )
  192.     D0                       A0       D0      A1    D1
  193.  
  194.     LONG CopyFromNetBuff( struct NetBuff *, LONG, UBYTE *, ULONG );
  195.  
  196.    FUNCTION
  197.     This function copies 'Count' bytes from a NetBuff to memory
  198.     pointed to by Data. If Offset is non-negative, then the start
  199.     of the data to copy is 'Offset' bytes from the start of the
  200.     NetBuff. If Offset is negative, then the start of the data to
  201.     copy is 'abs(Offset)' bytes from the end of the NetBuff.
  202.  
  203.    INPUTS
  204.     NetBuff         Pointer to NetBuff structure with source data.
  205.     Offset          Offset into Netbuff where data starts.
  206.     Data            Pointer to area to store data in.
  207.     Count           Number of bytes to copy.
  208.  
  209.    RESULTS
  210.     error           Zero if successful; non-zero otherwise.
  211.  
  212.    NOTES
  213.     This function may be called from interrupts.
  214.  
  215.     This function might be used by a network device driver to
  216.     extract bytes from a NetBuff to fill hardware.
  217.  
  218.     This function might be used within a protocol stack to extract
  219.     data structures from a NetBuff into local memory.
  220.  
  221.    SEE ALSO
  222.     netbuff.library/CopyToNetBuff()
  223.  
  224.    BUGS
  225.  
  226. netbuff.library/CopyNetBuff()                   netbuff.library/CopyNetBuff()
  227.  
  228.    NAME
  229.     CopyNetBuff -- Make a copy of a NetBuff.
  230.  
  231.    SYNOPSIS
  232.     error = CopyNetBuff( Netbuff0, Netbuff1 )
  233.     D0                   A0        A1
  234.  
  235.     LONG CopyNetBuff( struct NetBuff *, struct NetBuff * );
  236.  
  237.    FUNCTION
  238.     This function makes NetBuff1 a logical clone of Netbuff0.
  239.     Netbuff0 will be unmodified and Netbuff1 will be optimal.
  240.  
  241.     All data in Netbuff1 will be lost when this function is
  242.     called.
  243.  
  244.    INPUTS
  245.     Netbuff0        Pointer to source NetBuff structure.
  246.     Netbuff1        Pointer to destination NetBuff structure.
  247.  
  248.    RESULTS
  249.     error           Zero if successful; non-zero otherwise.
  250.  
  251.    NOTES
  252.     This function may be called from interrupts.
  253.  
  254.     Only the first NetBuffSegment in NetBuff1 is guaranteed to
  255.     still be in NetBuff1 when this function returns.
  256.  
  257.    SEE ALSO
  258.     netbuff.library/CopyFromNetBuff(),
  259.     netbuff.library/CopyToNetBuff()
  260.  
  261.    BUGS
  262.  
  263. netbuff.library/CopyToNetBuff()               netbuff.library/CopyToNetBuff()
  264.  
  265.    NAME
  266.     CopyToNetBuff -- Replace data in a NetBuff.
  267.  
  268.    SYNOPSIS
  269.     error = CopyToNetBuff( Netbuff, Offset, Data, Count )
  270.     D0                     A0       D0      A1    D1
  271.  
  272.     LONG CopyToNetBuff( struct NetBuff *, LONG, UBYTE *, ULONG );
  273.  
  274.    FUNCTION
  275.     This function replaces existing data in Netbuff with 'Count'
  276.     bytes from those pointed to by Data. If Offset is
  277.     non-negative, then the replacement starts 'Offset' bytes from
  278.     the start of Netbuff. If Offset is negative, then the
  279.     replacement starts 'abs(Offset)' from the end of Netbuff.
  280.  
  281.     This function will not change the amount of data that Netbuff
  282.     contains; it will only replace parts of it.
  283.  
  284.    INPUTS
  285.     Netbuff         Pointer to NetBuff structure to copy data to.
  286.     Offset          Offset into NetBuff to place data.
  287.     Data            Pointer to data to copy.
  288.     Count           Number of bytes of data to copy.
  289.  
  290.    RESULTS
  291.     error           Zero if successful; non-zero otherwise.
  292.  
  293.    NOTES
  294.     This function may be called from interrupts.
  295.  
  296.     This function might be used within a network device driver to
  297.     fill a NetBuff from bytes taken from the hardware. In this
  298.     case, CopyToNetBuff()s would be preceded possibly by a call to
  299.     ReadyNetBuff().
  300.  
  301.    SEE ALSO
  302.     netbuff.library/CopyFromNetBuff(),
  303.     netbuff.library/ReadyNetBuff()
  304.  
  305.    BUGS
  306.  
  307. netbuff.library/FreeSegments()                 netbuff.library/FreeSegments()
  308.  
  309.    NAME
  310.     FreeSegments -- Return a list of NetBuffSegments.
  311.  
  312.    SYNOPSIS
  313.     FreeSegments( Segment_list )
  314.                   A0
  315.  
  316.     void FreeSegments( struct List * );
  317.  
  318.    FUNCTION
  319.     This function gives a list of NetBuffSegments to the system
  320.     free pool.
  321.  
  322.    INPUTS
  323.     Segment_list    Pointer to the list of NetBuffSegments to add
  324.                         to the system free NetBuffSegment pool.
  325.  
  326.    NOTES
  327.     When this routine encounters a NetBuffSegment with
  328.     PhysicalSize of 0, the data area is left untouched but the
  329.     NetBuffSegment structure which points to the data is freed
  330.     using exec.library/FreeMem().
  331.  
  332.    SEE ALSO
  333.     netbuff.library/IntFreeSegments(),
  334.     netbuff.library/AllocSegments(),
  335.     netbuff.library/ReadyNetBuff()
  336.  
  337.    BUGS
  338.  
  339. netbuff.library/IntAllocSegments()         netbuff.library/IntAllocSegments()
  340.  
  341.    NAME
  342.     IntAllocSegments -- Get a list of NetBuffSegments.
  343.  
  344.    SYNOPSIS
  345.     IntAllocSegments( Count, Segment_List )
  346.                       D0     A0
  347.  
  348.     void IntAllocSegments( ULONG, struct List * );
  349.  
  350.    FUNCTION
  351.     This function returns a list of NetBuffSegments sufficient to
  352.     hold Count bytes.
  353.  
  354.    INPUTS
  355.     Count           Numbers of bytes for which space is needed.
  356.     Segment_List    Pointer to an empty (initialized) list to hold
  357.                         the allocated NetBuffSegments.
  358.  
  359.    RESULTS
  360.  
  361.    NOTES
  362.     The function should be called only from interrupts.
  363.  
  364.    SEE ALSO
  365.     netbuff.library/AllocSegments(),
  366.     netbuff.library/IntFreeSegments(),
  367.     netbuff.library/ReadyNetBuff()
  368.  
  369.    BUGS
  370.     Since this function may be called from interrupts, it can not
  371.     actually allocate memory from the system. It, therefor, relies
  372.     on a "friendly" task or process to add NetBuffSegments to the
  373.     free pool via the netbuff.library/FreeSegments() function.
  374.  
  375. netbuff.library/IntFreeSegments()           netbuff.library/IntFreeSegments()
  376.  
  377.    NAME
  378.     IntFreeSegments -- Return a list of NetBuffSegments.
  379.  
  380.    SYNOPSIS
  381.     IntFreeSegments( Segment_list )
  382.                      A0
  383.  
  384.     void IntFreeSegments( struct List * );
  385.  
  386.    FUNCTION
  387.     This function gives a list of NetBuffSegments to the system
  388.     free pool.
  389.  
  390.    INPUTS
  391.     Segment_list    Pointer to the list of NetBuffSegments to add
  392.                         to the system free NetBuffSegment pool.
  393.  
  394.    NOTES
  395.     The function should be called only from interrupts.
  396.  
  397.     When this routine encounters a NetBuffSegment with
  398.     PhysicalSize of 0, that data area is left untouched but the
  399.     NetBuffSegment structure which points to the data is freed
  400.     using exec.library/FreeMem().
  401.  
  402.    SEE ALSO
  403.     netbuff.library/FreeSegments(),
  404.     netbuff.library/IntAllocSegments(),
  405.     netbuff.library/ReadyNetBuff()
  406.  
  407.    BUGS
  408.     This function relies on the non-interrupt functions to perform
  409.     garbage collection of segments of physical size zero.
  410.  
  411. netbuff.library/IsContiguous()                 netbuff.library/IsContiguous()
  412.  
  413.    NAME
  414.     IsContiguous -- Checks if data in in contiguous memory.
  415.  
  416.    SYNOPSIS
  417.     result = IsContiguous( Netbuff, Offset, Count )
  418.     D0                     A0       D0      D1
  419.  
  420.     LONG IsContiguous( struct NetBuff *, LONG, ULONG );
  421.  
  422.    FUNCTION
  423.     This function indicates whether or not Count bytes of data
  424.     starting at Offset in NetBuff are in contiguous bytes. If
  425.     Offset is non-negative, then the start of the data to check is
  426.     'Offset' bytes from the start of the NetBuff. If Offset is
  427.     negative, then the start of the data to check is 'abs(Offset)'
  428.     bytes from the end of the NetBuff.
  429.  
  430.    INPUTS
  431.     Netbuff         Pointer to NetBuff to check.
  432.     Offset          Offset into NetBuff where to check.
  433.     Count           Number of bytes that should be contiguous.
  434.  
  435.    RESULTS
  436.     result          Zero if non-contiguous; non-zero otherwise.
  437.  
  438.    NOTES
  439.  
  440.    SEE ALSO
  441.  
  442.    BUGS
  443.  
  444. netbuff.library/NetBuffAppend()               netbuff.library/NetBuffAppend()
  445.  
  446.    NAME
  447.     NetBuffAppend -- Append one NetBuff to then end of another.
  448.  
  449.    SYNOPSIS
  450.     error = NetBuffAppend( Netbuff0, Netbuff1 )
  451.     D0                     A0        A1
  452.  
  453.     LONG NetBuffAppend( struct NetBuff *, struct NetBuff * );
  454.  
  455.    FUNCTION
  456.     This function appends the contents of Netbuff1 to the end of
  457.     Netbuff0.
  458.  
  459.    INPUTS
  460.     Netbuff0        NetBuff to be appended to.
  461.     Netbuff1        NetBuff to append.
  462.  
  463.    RESULTS
  464.     error           Zero if successful; non-zero otherwise.
  465.  
  466.    NOTES
  467.  
  468.    SEE ALSO
  469.     netbuff.library/PrependNetBuff(),
  470.     netbuff.library/SplitNetBuff()
  471.  
  472.    BUGS
  473.  
  474. netbuff.library/PrependNetBuff()             netbuff.library/PrependNetBuff()
  475.  
  476.    NAME
  477.     PrependNetBuff -- Prepend one NetBuff to the front of another.
  478.  
  479.    SYNOPSIS
  480.     error = PrependNetBuff( Netbuff0, Netbuff1 )
  481.     D0                      A0        A1
  482.  
  483.     LONG PrependNetBuff( struct NetBuff *, struct NetBuff * );
  484.  
  485.    FUNCTION
  486.     This function prepends the contents of Netbuff1 to the front
  487.     of Netbuff0.
  488.  
  489.    INPUTS
  490.     Netbuff0        NetBuff to be prepended to.
  491.     Netbuff1        NetBuff to prepend.
  492.  
  493.    RESULTS
  494.     error           Zero if successful; non-zero otherwise.
  495.  
  496.    NOTES
  497.  
  498.    SEE ALSO
  499.     netbuff.library/NetBuffAppend(),
  500.     netbuff.library/SplitNetBuff()
  501.  
  502.    BUGS
  503.  
  504. netbuff.library/ReadyNetBuff()                 netbuff.library/ReadyNetBuff()
  505.  
  506.    NAME
  507.     ReadyNetBuff -- Ready a NetBuff for copying to.
  508.  
  509.    SYNOPSIS
  510.     error = ReadyNetBuff( Netbuff, Count )
  511.     D0                    A0       D0
  512.  
  513.     LONG ReadyNetBuff( struct NetBuff *, ULONG );
  514.  
  515.    FUNCTION
  516.     This function sets the amount of data refered to by a NetBuff,
  517.     and the associated NetBuffSegments, to Count bytes in
  518.     preparation for a CopyToNetBuff() operation. It does not
  519.     initialize the data in the NetBuff.
  520.  
  521.    INPUTS
  522.     Netbuff         Pointer to NetBuff structure to initialize.
  523.     Count           The number of bytes of data that the NetBuff
  524.                         is to refer to.
  525.  
  526.    RESULTS
  527.     error           Zero if successful; non-zero otherwise.
  528.  
  529.    NOTES
  530.     This function may be called from interrupts.
  531.  
  532.     This function will attempt to allocate NetBuffSegments as
  533.     needed to make room for Count bytes available.
  534.  
  535.     Unneeded NetBuffSegments will be returned to the system free
  536.     pool.
  537.  
  538.    SEE ALSO
  539.  
  540.    BUGS
  541.  
  542. netbuff.library/ReclaimSegments()           netbuff.library/ReclaimSegments()
  543.  
  544.    NAME
  545.     ReclaimSegments -- Free all but first NetBuffSegment.
  546.  
  547.    SYNOPSIS
  548.     error = ReclaimSegments( Netbuff )
  549.     D0                       A0
  550.  
  551.     LONG ReclaimSegments( struct NetBuff * );
  552.  
  553.    FUNCTION
  554.     This function frees all non-zero PhysicalSize NetBuffSegments
  555.     except the first NetBuffSegment of the NetBuff.
  556.  
  557.    INPUTS
  558.     Netbuff         Pointer to NetBuff to reclaim segments from.
  559.  
  560.    RESULTS
  561.     error           Zero if successful; non-zero otherwise.
  562.  
  563.    NOTES
  564.     This function may be called from interrupts.
  565.  
  566.     The intended use for this function is to encourage drivers or
  567.     protocol stacks to free NetBuffSegments from NetBuffs in read
  568.     queues.
  569.  
  570.    SEE ALSO
  571.  
  572.    BUGS
  573.  
  574. netbuff.library/SplitNetBuff()                 netbuff.library/SplitNetBuff()
  575.  
  576.    NAME
  577.     SplitNetBuff -- Split a NetBuff in to two NetBuffs.
  578.  
  579.    SYNOPSIS
  580.     error = SplitNetBuff( Netbuff0, Count, Netbuff1 )
  581.     D0                    A0        D0     A1
  582.  
  583.     LONG SplitNetBuff( struct NetBuff *, LONG, struct NetBuff * );
  584.  
  585.    FUNCTION
  586.     This function takes a NetBuff and splits it at the specified
  587.     offset. The sign of Count determines which bytes will be
  588.     removed from Netbuff0 and placed in Netbuff1. If Count is
  589.     non-negative, the first 'Offset' bytes in Netbuff0 will be
  590.     moved to Netbuff1. If Offset is negative, the last
  591.     'abs(Offset)' bytes in Netbuff0 will be moved to Netbuff1.
  592.  
  593.     All data in Netbuff1 will be lost when this function is
  594.     called.
  595.  
  596.    INPUTS
  597.     Netbuff0        Pointer to NetBuff structure with data to
  598.                         split.
  599.     Count           Number of bytes to split off.
  600.     Netbuff1        Pointer to a NetBuff structure to receive
  601.                         split-off data.
  602.  
  603.    RESULTS
  604.     error           Zero if successful; non-zero otherwise.
  605.  
  606.    NOTES
  607.     This function might be used within a protocol stack to split
  608.     a packet into smaller NetBuffs so as to fall below a specific
  609.     transport medium's maximum transfer unit.
  610.     
  611.    SEE ALSO
  612.     netbuff.library/TrimNetBuff(),
  613.     netbuff.library/NetBuffAppend(),
  614.     netbuff.library/PrependNetBuff()
  615.  
  616.    BUGS
  617.     If the split point is in a NetBuffSegment of PhysicalSize
  618.     zero, exec/AllocMem() will be called to create a new segment
  619.     of PhysicalSize zero.
  620.  
  621. netbuff.library/TrimNetBuff()                   netbuff.library/TrimNetBuff()
  622.  
  623.    NAME
  624.     TrimNetBuff -- Elliminate leading or trailing data.
  625.  
  626.    SYNOPSIS
  627.     error = TrimNetBuff( Netbuff, Count )
  628.     D0                   A0        D0
  629.  
  630.     LONG TrimNetBuff( struct NetBuff *, LONG );
  631.  
  632.    FUNCTION
  633.     This function takes a NetBuff and elliminates 'abs(Count)'
  634.     bytes of data from the first or last bytes of the NetBuff data
  635.     depending on the sign of Count. If Count is positive, the
  636.     first 'Count' bytes of data are elliminated. If Count is
  637.     negative, the last 'abs(Count)' bytes are elliminated.
  638.  
  639.     Emptied NetBuffSegments (which may result) will be returned to
  640.     the free pool.
  641.  
  642.    INPUTS
  643.     Netbuff         Pointer to NetBuff to be trimmed.
  644.     Count           Number of data bytes to remove.
  645.  
  646.    RESULTS
  647.     error           Zero if successful; non-zero otherwise.
  648.  
  649.    NOTES
  650.     This function might be used within a protocol stack to remove
  651.     levels of protocol wrapping from either side of a packet.
  652.  
  653.    SEE ALSO
  654.     netbuff.library/SplitNetBuff(),
  655.     netbuff.library/NetBuffAppend(),
  656.     netbuff.library/PrependNetBuff()
  657.  
  658.    BUGS
  659.  
  660.  
  661.